package org.flexthinker.binding.ui.form.binding
{
    import flash.display.DisplayObject;

    import org.flexthinker.binding.bean.Binding;

    import org.flexthinker.binding.form.FormModel;

    /**
     * Represents a specialized <code>Binding</code> for UI Components.
     * <code>FormBinding</code> works with <code>Binder</code> implementations in order to bind a visual form
     * to a domain object.</code>
     * <p>
     * Binders should know more about particular components,
     * as compared to regular <code>Binding</code>s.
     * Binders know which BindingStrategy applies for a component,
     * which property of that component they should bind to.
     * </p>
     * <p>
     * For example a <code>Label</code> could have a <code>FieldBinder</code> that binds to the <code>text</code> property,
     * while a <code>List</code> could have a <code>ListBinder</code>, which binds to the <code>selectedIndex</code> property.
     * </p>
     */
    public interface Binder
    {
        /**
         * Method called from the constructor of <code>AbstractBinder</code>.
         * <p>
         *     This method won't be displayed in the IDE, when the interface is used.
         *     Its purpose is to indicate that a <code>Binder</code> can exist
         *     only if there is a visual component and a property to be used as the source for binding.
         * </p>
         * @param component
         *          The UI Component to display the value provided by <code>formProperty</code>
         * @param formProperty
         *          The name of the property to be bounded to the <code>component</code>
         */
        function Binder(component:DisplayObject, formProperty:String):void

        /**
         *
         * Creates a specialized Binding, from the <code>formModel</code> source.
         *
         * <p>
         *     First call returns a new <code>Binding</code>.
         *     Consecutive calls return same <code>Binding</code> instance.
         *     </p>
         * @param formModel
         *          the source for the Binding
         *
         * @see org.flexthinker.binding.bean.Binding
         */
        function getBinding(formModel:FormModel):Binding;

         /**
         * Returns the target visual component which will display the binding source.
         * @return
         *      The visual object used as the target for the binding
         */
        function getComponent():DisplayObject;

        /**
         * Returns the name of the property.
         * @return
         *      The name of the property used as the source property for binding.
         */
        function getFormProperty():String;

    }
}
